home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / p4 / p4-1_2b.lha / p4-1.2b / alog / README_ALOG < prev   
Text File  |  1992-10-19  |  5KB  |  174 lines
  1.  --------------------------------------------------------------------
  2.  | README (Summary documentation for the ALOG Tracing package)      |
  3.  |                                                                  |
  4.  | This file briefly describes the functionality  and the user      |
  5.  | interface for the ALOG system.                                   |
  6.  |                                                                  |
  7.  | Written by:  Arun Nanda    (08/15/91)                            |
  8.  |                                                                  |
  9.  --------------------------------------------------------------------
  10.  
  11. This directory contains the source file for the tracing system.
  12. The code presented here can be transported to any of the following 
  13. computers:
  14.  
  15.                 ALLIANT
  16.                 BALANCE
  17.                 BFLY1
  18.                 BFLY2
  19.                 BFLY2_TCMP
  20.                 DELTA
  21.                 IBM3090
  22.                 RS6000
  23.                 IPSC860_HOST
  24.                 IPSC860_NODE
  25.                 MULTIMAX
  26.                 NEXT
  27.                 SGI
  28.                 SUN
  29.                 SYMMETRY
  30.                 TITAN
  31.  
  32. To add more configurations, follow the examples of ifdefs for the Machine
  33. dependent code sections.  The microsecond clock provided by the USC
  34. package is used by ALOG to obtain the event timestamps.  Hence, all
  35. timestamps appearing in the log files are expressed in microseconds.
  36.  
  37.  
  38. ALOG TRACING INTERFACE
  39. ======================
  40.  
  41. The package comprises of the following macros/functions that are
  42. provided via the include file "alog.h" and the library "libalog.a".
  43.  
  44.  
  45.     ALOG_DEC:    
  46.  
  47.         no parameters 
  48.  
  49.         This macro is now redundant, but retained only for 
  50.         backward compatibility.
  51.  
  52.  
  53.     ALOG_SETUP(pid,flag):    
  54.  
  55.         pid  -  (integer) process id of callee
  56.         flag -  (integer) either ALOG_WRAP or ALOG_TRUNCATE  
  57.  
  58.         This macros initializes the tracing area for a slave 
  59.         process and MUST be called once before any event is 
  60.         logged.  If the value of 'flag' is set to ALOG_WRAP, 
  61.         then in the event of no more space for logging events 
  62.         the system will only report the latest n events.  If 
  63.         the 'flag' is set to ALOG_TRUNCATE the system will stop 
  64.         logging events as soon as there is no more memory for 
  65.         the events to be logged.
  66.  
  67.  
  68.     ALOG_MASTER(pid,flag):
  69.  
  70.         pid  -  (integer) process id of the callee
  71.         flag -  (integer) either 0 or 1  (see above)
  72.  
  73.         This macro has the same effect over its parameters as
  74.         ALOG_SETUP with the difference that this macro should be 
  75.         referenced by the master process only.
  76.  
  77.  
  78.     ALOG_DEFINE(event,strdef,format):
  79.  
  80.         event  - (integer) id of event being defined
  81.         strdef - (string) description of 'event'
  82.         format - (string) control string in "printf" format to
  83.  
  84.         This macro expands to an event definition code.
  85.  
  86.  
  87.     ALOG_LOG(pid,event,intdata,strdata):
  88.  
  89.         pid     - (integer) process id of callee
  90.         event   - (integer) event id to be logged
  91.         intdata - (integer) any integer data for this event
  92.         strdata - (string) any string data (can be the null string)
  93.  
  94.         This macro provides the event logging service.
  95.  
  96.  
  97.     ALOG_OUTPUT:
  98.         no parameters  
  99.  
  100.         This macro dumps the events logged into a log file with
  101.         the name "alogfile.pxx" where 'xx' is the logical PID
  102.         of the callee process.  The log file is created in the
  103.         current directory unless specified otherwise through
  104.         the macro ALOG_SETDIR.
  105.  
  106.  
  107.     ALOG_SETDIR(dir):
  108.  
  109.         dir - (string) directory where log file is created
  110.  
  111.         This macro sets the output directory for the log file.
  112.         The default directory for the creation of the log file
  113.         is the current directory of the process.  If used, then
  114.         this macro MUST be invoked before ALOG_MASTER/ALOG_SETUP.
  115.  
  116.  
  117.     ALOG_STATUS(status):
  118.  
  119.         status - (integer) either ALOG_ON or ALOG_OFF
  120.  
  121.         This macro controls the logging status of ALOG as follows.
  122.         Setting 'status' to ALOG_ON enables logging until it is
  123.         turned off.  Setting 'status' to ALOG_OFF disables logging 
  124.         until it is turned on again.  Logging is enabled at the 
  125.         outset by default.
  126.  
  127.  
  128.     ALOG_ENABLE:
  129.  
  130.         no parameters
  131.  
  132.         This macro enables event logging; same as calling
  133.         ALOG_STATUS(ALOG_ON).
  134.  
  135.  
  136.     ALOG_DISABLE:
  137.  
  138.         no parameters
  139.  
  140.         This macro disables event logging; same as calling
  141.         ALOG_STATUS(ALOG_OFF).
  142.  
  143. An application that uses the ALOG tracing facility must do the
  144. following:
  145.  
  146.  1) Include the file "alog.h" at the beginning of the program.
  147.  2) Link the application with the library file "libalog.a" and the
  148.     machine-specific library mentioned below.
  149.  
  150.  
  151. INCLUDE FILE
  152. ============
  153.  
  154.         alog.h
  155.  
  156.  
  157. LIBRARY FILE
  158. ============
  159.  
  160.         libalog.a
  161.  
  162.  
  163. ADDITIONAL MACHINE DEPENDENT LIBRARIES
  164. ======================================
  165.  
  166. The application will also have to be linked with the following machine
  167. dependent libraries in order to enable the microsecond clock to function
  168. properly:
  169.  
  170.                  MULTIMAX        -lpp
  171.                  BALANCE         -lseq
  172.                  SYMMETRY        -lseq
  173.  
  174.